Inside Macintosh: Programming With JManager /

Chapter 1 - Using JManager

Creating an AWT Context

On the Mac OS, an AWT context is defined by a JMAWTContextRef object. Every Java program running within a session has its own AWT context. You can create an AWT context before or after instantiating a locator for the applet you want to run, but you must instantiate the AWT context before instantiating the applet.

To instantiate a JMAWTContextRef object, you call the JMNewAWTContext function as shown in Listing 1-7. You must have instantiated a session already before creating an AWT context.

Listing 1-7 Creating an AWT context

/* define callbacks for the AWT context */
JMAWTContextCallbacks sessionCallbacks = {
   kJMVersion,    /* should be kJMVersion */
   MyRequestFrame,/* callback to create a frame */
   MyReleaseFrame,/* callback to release a frame */
   MyUniqueMenuID,/* callback to give the AWT a valid MenuID */
   MyExceptionOccurred,/* notify that an exception occurred */
   };

/* create an AWT context for this applet */
JMAWTContextRef context;
err = JMNewAWTContext(&context, theSession, &sessionCallbacks, 0);

The value context references the JMAWTContext object, and you should pass this value in other JManager functions to specify this particular context.

You must specify a number of callbacks when calling JMNewAWTContext. JManager uses these callbacks to handle requests from the Java program for new frames (that is, windows). The MyRequestFrame callback creates a new window, MyReleaseFrame releases a window , and MyUniqueMenuID creates a new menu ID . For example, if the Java program requests that a frame be made available, the application-defined callback function MyRequestFrame should request a new Mac OS window. Listing 1-8 shows an example of such a function.

Listing 1-8 Application-defined new frame function

OSStatus MyRequestFrame(JMAWTContextRef context, JMFrameRef newFrame,
   JMFrameKind kind, Rect bounds, Boolean resizeable,
   JMFrameCallbacks* callbacks)
{
   WindowPtr win;
   Point zeroPt = { 0, 0 };
   
   /* callbacks with pointers to your implementation-- */
   /* note that you also fill in the version number that you */
   /* compiled against (based on what you passed to JMOpenSession) */ 

   callbacks->fVersion = kJMVersion;
   callbacks->fSetFrameSize = MyResizeRequest;
   callbacks->fInvalRect = MyInvalRect;
   callbacks->fShowHide = MyShowHide;
   callbacks->fSetTitle = MySetTitle;
   callbacks->fCheckUpdate = MyCheckUpdate;
   callbacks->fReorderFrame = MyFrameReorder
   callbacks->fSetResizeable = MySetResizeable
      
   win = NewCWindow(nil, &bounds, "\p", false, documentProc, 
      (WindowPtr) -1, true, (long) newFrame);
   if (win == nil)
      return memFullErr;

   JMSetFrameVisibility(newFrame, win, zeroPt, nil);

   return JMSetFrameData(newFrame, (JMClientData) win);
}

The MyRequestFrame function in this example calls the Mac OS Toolbox function NewCWindow to request a new window that corresponds to the frame. If you prefer, you can use an existing window instead. This example always creates a window of type documentProc (a simple document window without size or zoom boxes), but you can select different window types depending on the kind parameter passed into the callback function. See "Frame Types" for a listing of possible requests.

After creating the window, the JMSetFrameVisibility function registers the window characteristics (the graphics port, its position, and its clipping region) with the frame. Whenever the visibility of the window changes (for example, due to scrolling), you must call JMSetFrameVisibility again to update the visibility information.

The function MyRequestFrame also requires a number of callback functions that allow the Java program to manipulate the new window (for example, to show, hide, or update the window). For more information on these functions, see "Displaying Frames" and "Application-Defined Functions".

As part of the NewCWindow call, the reference to the frame (as held in newFrame) is stored in the refCon field of the window record (a WindowRecord structure). Doing so allows you to determine the frame associated with a window by simply calling the Mac OS Toolbox function GetWRefCon.

In a similar fashion, the JMSetFrameData function is used to store a pointer to the new window record in the frame's client data. You can then easily determine the window associated with a given frame by using a function such as that in Listing 1-9.

Listing 1-9 Determining the window associated with a frame

WindowPtr getFrameWindow(JMFrameRef frame)
{
   if (frame) {
      WindowPtr win = nil;
      if (JMGetFrameData(frame, (JMClientData*) &win) == noErr)
         return win;
   }
   return nil;
}

Displaying Frames

As explained earlier, a Java program displays graphical output in virtual windows called frames. Since frames correspond to Mac OS windows, you can manipulate them in a similar manner (for example, create or destroy frames, resize them, and so on).

In order to communicate between the abstract frames and the actual Mac OS windows, you must designate a number of application-defined callback functions. Many of these functions correspond to similar Mac OS Toolbox functions. The application-defined functions and their corresponding Mac OS Toolbox functions are shown in Table 1-1. For details of the structure of these functions, see "Application-Defined Functions".

Table 1-1 Application-defined frame functions

Frame function	Description	Corresponding Mac OS Toolbox function
MyRequestFrame	Creates a new window	GetNewCWindow, NewCWindow, GetNewWindow, or NewWindow
MyReleaseFrame	Disposes of a window	DisposeWindow
MyResizeRequest	Requests that a window be resized	SizeWindow
MyInvalRect	Invalidates a portion of a window	InvalRect
MyShowHide	Shows or hides a window	ShowHide or ShowWindow and HideWindow
MySetTitle	Sets the window title bar	SetWTitle
MyCheckUpdate	Checks to see if a window update is necessary	CheckUpdate or BeginUpdate and EndUpdate
MyFrameReorder	Changes the ordering of the frame (bring to front, send to back, etc)	BringToFront or SendBehind
MySetResizeable	Sets whether a frame is resizeable or not	No corresponding function, although the state set by this function affects whether your DoGrowWindow callback calls the SizeWindow function.

Typically the bulk of an application-defined frame function prepares a call to the corresponding Mac OS Toolbox function. For example, assuming that the application uses the functions in Listing 1-8 and Listing 1-9, you can use the callback function in Listing 1-10 to set the window title.

Listing 1-10 A callback function to change the title of a window

void MySetTitle(JMFrameRef frame, JMTextRef titleObj)
{
   Handle title; 
   Str255 ptitle;

   title = JMTextToMacOSCStringHandle(titleObj);
   Hlock(title);

   convertToPascalString(*title, &ptitle); /* this is a dummy utility */

   WindowPtr win = getFrameWindow(frame);
   if (win)
      SetWTitle(win, ptitle);

   HUnlock(title);
   DisposeHandle(title); 
}

Since the Mac OS Toolbox function SetWTitle requires a Pascal string, you must convert the handle title before calling SetWTitle.

Getting Information About AWT Contexts and Frames

JManager provides a number of functions that return information about an AWT context or a frame. For example, since multiple applets can appear onscreen, if a user clicks in a window that corresponds to a frame, you may need to find out what applet or AWT context the frame belongs to.

The JMCountAWTContextFrames function counts the number of frames associated with an AWT context.

The JMGetAWTContextFrame function lets you find a particular frame (as indexed by the JMCountAWTContextFrames function) associated with an AWT context.

The JMGetFrameContext function finds the AWT context associated with a frame.

The JMGetFrameViewer function lets you determine the frame associated with an applet.

The JMGetViewerFrame function finds an applet's parent frame, which is the frame created when the applet is created.

If you want to set or read client-specific data associated with an AWT context, you can do so using the functions JMSetAWTContextData and JMGetAWTContextData .

If you want to read or set client-specific data associated with a particular frame, you can do so using the functions JMGetFrameData and JMSetFrameData . You can store the window record as client data to make it easy to find a window corresponding to a frame. See Listing 1-8 and Listing 1-9 for an example.

Removing an AWT Context

When you have finished executing an applet and no longer need the AWT context, you should dispose of it using the JMDisposeAWTContext function . However, you should have already removed any applets from the context before calling JMDisposeAWTContext. You can reuse an AWT context by disposing of an instantiated applet and then instantiating a new one in the same context.

---

Subtopics

Displaying Frames

Getting Information About AWT Contexts and Frames

Removing an AWT Context